<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html><head>









 
 
 

  
  
  




  
    
<meta http-equiv="content-type" content="text/html; charset=utf-8"><title>RESTful API Specification - OpenSocial - Google Code</title>

<script type="text/javascript">
(function(){function a(){this.t={};this.tick=function(c){this.t[c]=(new Date).getTime()};this.tick("start")}var b=new a;window.jstiming={Timer:a,load:b};if(window.external&&window.external.pageT)window.jstiming.pt=window.external.pageT;})();

var _tocPath_ = '/html/apis/opensocial/docs/_toc.ezt';
</script>
<link href="restfulspec_files/codesite.css" type="text/css" rel="stylesheet">
<script src="restfulspec_files/codesite.js" type="text/javascript"></script>
<link rel="search" type="application/opensearchdescription+xml" title="Google Code" href="http://code.google.com/osd.xml"><!--[if IE]><link rel="stylesheet" type="text/css" href="/css/iehacks.css" /><![endif]-->



    <link href="restfulspec_files/semantic_headers.css" rel="stylesheet" type="text/css"></head><body class="gc-documentation">

    
    
    <div id="gc-container">
<a name="top"></a>
<div id="skipto">
  <a href="#gc-pagecontent">Skip to page content</a>
  <a href="#gc-toc">Skip to main navigation</a>
</div>
<div id="langpref">    
   <a style="text-decoration: none; cursor: pointer;" class="dropdown" href="http://code.google.com/"><span class="title1219980363812" style="text-decoration: underline;">English</span><span style="vertical-align: middle; text-decoration: none; font-family: arial,sans-serif; font-size: 11px;">&nbsp;▼</span></a>
   <span>|</span>
   <a href="http://code.google.com/more/">Site Directory</a>
</div>
<div id="gc-header">
  <div id="logo"><a href="http://code.google.com/">
  
     <img src="restfulspec_files/cleardot.gif" alt="Google Code Home Page" id="gc-logo-img" height="1" width="1">
  
  </a></div>
  <div id="search">
    <div id="searchForm" class="searchForm" style="">
      <form action="" accept-charset="utf-8" class="gsc-search-box" onsubmit="executeGSearch(document.getElementById('gsearchInput').value); return false;">
        <table class="gsc-search-box" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td class="gsc-input">
                <input id="gsearchInput" name="q" maxlength="2048" class="gsc-input" autocomplete="off" title="Google Code Search" style="width: 345px;" type="text">
              </td>
              <td class="gsc-search-button">
                <div id="cs-searchresults" onclick="event.cancelBubble = true;"></div>
                <input title="Search" id="gsearchButton" class="gsc-search-button" value="Search" type="submit">
              </td>
            </tr>
            <tr>
              <td class="greytext">e.g. "ajax apis" or "open source"</td>
            </tr>
          </tbody>
        </table>
      </form>
    </div> <!-- end searchForm -->
    <div id="searchForm2" class="searchForm2" style="display: none;">
      <form id="cse" action="http://www.google.com/cse">
        <input name="cref" value="http://code.google.com/cse/googlecode-context.xml" type="hidden">
        <input name="q" maxlength="2048" autocomplete="off" title="Google Code Search" style="width: 345px;" type="text">
        <input name="sa" value="Search" title="Search" type="submit"><br>
        <div class="greytext">e.g. "ajax apis" or "open source"</div>
      </form>
    </div> <!-- end searchForm2 -->
  </div> <!-- end search -->
</div> <!-- end gc-header -->


<div id="codesiteContent">

<a name="gc-topnav-anchor"></a>
<div id="gc-topnav">
  <h1>OpenSocial</h1>
  <ul id="docs" class="gc-topnav-tabs">

    <li id="home_link">
      <a href="http://code.google.com/apis/opensocial/" title="OpenSocial home page">Home</a>
    </li>
  
    <li id="docs_link">
      <a href="http://code.google.com/apis/opensocial/docs/index.html" class="selected" title="Official OpenSocial documentation">Docs</a>
    </li>
  
    <li id="faq_link">
      <a href="http://code.google.com/apis/opensocial/faq.html" title="Answers to frequently asked questions about OpenSocial">FAQ</a>
    </li>
  
    <li id="articles_link">
      <a href="http://code.google.com/apis/opensocial/articles/" title="Focused articles and tutorials for OpenSocial developers">Articles</a>
    </li>
  
    <li>
      <a href="http://opensocialapis.blogspot.com/" title="Official OpenSocial blog">Blog</a>
    </li>
  
    <li>
      <a href="http://groups.google.com/group/opensocial" title="OpenSocial developer forum">Group</a>
    </li>
  
    <li>
      <a href="http://code.google.com/apis/opensocial/terms.html" title="OpenSocial terms of service">Terms</a>
    </li>
  

  </ul>
</div> <!-- end gc-topnav -->

    <div class="g-section g-tpl-170">

      <div class="g-unit g-first" id="gc-toc">
          <ul class="treelist tlw-nested-only tlw-processed tlw-instance-0">
    <li><a href="http://code.google.com/apis/opensocial/partners.html">Who's Using It?</a></li>
    <li><a href="http://code.google.com/apis/opensocial/gettingstarted.html">Building Social Apps</a></li>
    <li><a href="http://code.google.com/apis/opensocial/container.html">Hosting OpenSocial Apps</a></li>
  </ul>

<div class="line"></div>

<ul class="treelist tlw-nested-only tlw-processed tlw-instance-1">
  <li><h1 class="tlw-ignore">JavaScript API</h1>
    <ul>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/devguide.html">Developer's Guide (v0.7)</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/releasenotes.html">Release Notes (v0.8)</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/spec.html">API Specification (v0.8)</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Collapse API Reference (v0.8)"><img src="restfulspec_files/cleardot.gif" alt="Collapse API Reference (v0.8)" class="tlw-control tlw-minus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/">API Reference (v0.8)</a></div><ul style="display: block;" id="1-sub-0">
     <!-- _sidenav.ezt doesn't work with the current scripts. Shakila is working on it. -->
      
<ul>
<li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Collapse opensocial"><img src="restfulspec_files/cleardot.gif" alt="Collapse opensocial" class="tlw-control tlw-minus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial">opensocial</a></div><ul style="display: block;" id="1-sub-1">
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Activity"><img src="restfulspec_files/cleardot.gif" alt="Expand Activity" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Activity">Activity</a></div><ul style="display: none;" id="1-sub-2">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Activity.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Address"><img src="restfulspec_files/cleardot.gif" alt="Expand Address" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Address">Address</a></div><ul style="display: none;" id="1-sub-3">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Address.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand BodyType"><img src="restfulspec_files/cleardot.gif" alt="Expand BodyType" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.BodyType">BodyType</a></div><ul style="display: none;" id="1-sub-4">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.BodyType.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Collection">Collection</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.CreateActivityPriority">CreateActivityPriority</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand DataRequest"><img src="restfulspec_files/cleardot.gif" alt="Expand DataRequest" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest">DataRequest</a></div><ul style="display: none;" id="1-sub-5">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest.DataRequestFields">DataRequestFields</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest.FilterType">FilterType</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest.PeopleRequestFields">PeopleRequestFields</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataRequest.SortOrder">SortOrder</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.DataResponse">DataResponse</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Email"><img src="restfulspec_files/cleardot.gif" alt="Expand Email" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Email">Email</a></div><ul style="display: none;" id="1-sub-6">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Email.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Enum"><img src="restfulspec_files/cleardot.gif" alt="Expand Enum" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum">Enum</a></div><ul style="display: none;" id="1-sub-7">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum.Drinker">Drinker</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum.Gender">Gender</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum.LookingFor">LookingFor</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum.Presence">Presence</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Enum.Smoker">Smoker</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Environment"><img src="restfulspec_files/cleardot.gif" alt="Expand Environment" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Environment">Environment</a></div><ul style="display: none;" id="1-sub-8">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Environment.ObjectType">ObjectType</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.EscapeType">EscapeType</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand IdSpec"><img src="restfulspec_files/cleardot.gif" alt="Expand IdSpec" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.IdSpec">IdSpec</a></div><ul style="display: none;" id="1-sub-9">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.IdSpec.Field">Field</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.IdSpec.PersonId">PersonId</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand MediaItem"><img src="restfulspec_files/cleardot.gif" alt="Expand MediaItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.MediaItem">MediaItem</a></div><ul style="display: none;" id="1-sub-10">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.MediaItem.Field">Field</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.MediaItem.Type">Type</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Message"><img src="restfulspec_files/cleardot.gif" alt="Expand Message" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Message">Message</a></div><ul style="display: none;" id="1-sub-11">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Message.Field">Field</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Message.Type">Type</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Name"><img src="restfulspec_files/cleardot.gif" alt="Expand Name" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Name">Name</a></div><ul style="display: none;" id="1-sub-12">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Name.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand NavigationParameters"><img src="restfulspec_files/cleardot.gif" alt="Expand NavigationParameters" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.NavigationParameters">NavigationParameters</a></div><ul style="display: none;" id="1-sub-13">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.NavigationParameters.DestinationType">DestinationType</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.NavigationParameters.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Organization"><img src="restfulspec_files/cleardot.gif" alt="Expand Organization" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Organization">Organization</a></div><ul style="display: none;" id="1-sub-14">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Organization.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Permission">Permission</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Person"><img src="restfulspec_files/cleardot.gif" alt="Expand Person" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Person">Person</a></div><ul style="display: none;" id="1-sub-15">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Person.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Phone"><img src="restfulspec_files/cleardot.gif" alt="Expand Phone" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Phone">Phone</a></div><ul style="display: none;" id="1-sub-16">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Phone.Field">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand ResponseItem"><img src="restfulspec_files/cleardot.gif" alt="Expand ResponseItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.ResponseItem">ResponseItem</a></div><ul style="display: none;" id="1-sub-17">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.ResponseItem.Error">Error</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Url"><img src="restfulspec_files/cleardot.gif" alt="Expand Url" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Url">Url</a></div><ul style="display: none;" id="1-sub-18">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Url.Field">Field</a>
  </li>
</ul>
  </li>
</ul>
</li>
</ul>

 

     <!-- Until that's fixed, we include _all_classes.ezt instead. -->
     <!--    
<ul>
<li><a href="#opensocial">opensocial</a>
<ul>
  <li><a href="#opensocial.Activity">Activity</a>
<ul>
  <li><a href="#opensocial.Activity.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Address">Address</a>
<ul>
  <li><a href="#opensocial.Address.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.BodyType">BodyType</a>
<ul>
  <li><a href="#opensocial.BodyType.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Collection">Collection</a>
  </li>
  <li><a href="#opensocial.CreateActivityPriority">CreateActivityPriority</a>
  </li>
  <li><a href="#opensocial.DataRequest">DataRequest</a>
<ul>
  <li><a href="#opensocial.DataRequest.DataRequestFields">DataRequestFields</a>
  </li>
  <li><a href="#opensocial.DataRequest.FilterType">FilterType</a>
  </li>
  <li><a href="#opensocial.DataRequest.PeopleRequestFields">PeopleRequestFields</a>
  </li>
  <li><a href="#opensocial.DataRequest.SortOrder">SortOrder</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.DataResponse">DataResponse</a>
  </li>
  <li><a href="#opensocial.Email">Email</a>
<ul>
  <li><a href="#opensocial.Email.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Enum">Enum</a>
<ul>
  <li><a href="#opensocial.Enum.Drinker">Drinker</a>
  </li>
  <li><a href="#opensocial.Enum.Gender">Gender</a>
  </li>
  <li><a href="#opensocial.Enum.LookingFor">LookingFor</a>
  </li>
  <li><a href="#opensocial.Enum.Presence">Presence</a>
  </li>
  <li><a href="#opensocial.Enum.Smoker">Smoker</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Environment">Environment</a>
<ul>
  <li><a href="#opensocial.Environment.ObjectType">ObjectType</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.EscapeType">EscapeType</a>
  </li>
  <li><a href="#opensocial.IdSpec">IdSpec</a>
<ul>
  <li><a href="#opensocial.IdSpec.Field">Field</a>
  </li>
  <li><a href="#opensocial.IdSpec.PersonId">PersonId</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.MediaItem">MediaItem</a>
<ul>
  <li><a href="#opensocial.MediaItem.Field">Field</a>
  </li>
  <li><a href="#opensocial.MediaItem.Type">Type</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Message">Message</a>
<ul>
  <li><a href="#opensocial.Message.Field">Field</a>
  </li>
  <li><a href="#opensocial.Message.Type">Type</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Name">Name</a>
<ul>
  <li><a href="#opensocial.Name.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.NavigationParameters">NavigationParameters</a>
<ul>
  <li><a href="#opensocial.NavigationParameters.DestinationType">DestinationType</a>
  </li>
  <li><a href="#opensocial.NavigationParameters.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Organization">Organization</a>
<ul>
  <li><a href="#opensocial.Organization.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Permission">Permission</a>
  </li>
  <li><a href="#opensocial.Person">Person</a>
<ul>
  <li><a href="#opensocial.Person.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Phone">Phone</a>
<ul>
  <li><a href="#opensocial.Phone.Field">Field</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.ResponseItem">ResponseItem</a>
<ul>
  <li><a href="#opensocial.ResponseItem.Error">Error</a>
  </li>
</ul>
  </li>
  <li><a href="#opensocial.Url">Url</a>
<ul>
  <li><a href="#opensocial.Url.Field">Field</a>
  </li>
</ul>
  </li>
</ul>
</li>
</ul>

 -->

     <!-- The following line is obsolete because (a) we don't include _all_classes.ezt -->
     <!-- any more, and (b) the extra tag in _all_classes.ezt has been fixed anyway. -->
     <!--     </ul></li>  -->
          <li style="padding-top: 0pt; padding-bottom: 0pt;"> 
              <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand gadgets (core)"><img src="restfulspec_files/cleardot.gif" alt="Expand gadgets (core)" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#core">gadgets (core)</a></div><ul style="display: none;" id="1-sub-19">
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.Prefs">Prefs</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand io"><img src="restfulspec_files/cleardot.gif" alt="Expand io" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io">io</a></div><ul style="display: none;" id="1-sub-20">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.AuthorizationType">AuthorizationType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.ContentType">ContentType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.MethodType">MethodType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.ProxyUrlRequestParameters">ProxyUrlRequestParameters</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.io.RequestParameters">RequestParameters</a></li>
        </ul>
      </li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.json">json</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.util">util</a></li>
    </ul>


          </li>
          <li style="padding-top: 0pt; padding-bottom: 0pt;"> 
              <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand gadgets (feature-specific)"><img src="restfulspec_files/cleardot.gif" alt="Expand gadgets (feature-specific)" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#features">gadgets (feature-specific)</a></div><ul style="display: none;" id="1-sub-21">
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.MiniMessage">MiniMessage</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.Tab">Tab</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.TabSet">TabSet</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.flash">flash</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.pubsub">pubsub</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.rpc">rpc</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;"> <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand skins"><img src="restfulspec_files/cleardot.gif" alt="Expand skins" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.skins">skins</a></div><ul style="display: none;" id="1-sub-22">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.skins.Property">Property</a></li>
      </ul></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;"> <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand views"><img src="restfulspec_files/cleardot.gif" alt="Expand views" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.views">views</a></div><ul style="display: none;" id="1-sub-23">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.views.View">View</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.views.ViewType">ViewType</a></li>
      </ul></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.8/reference/gadgets/#gadgets.window">window</a></li>
    </ul>

          </li>
        </ul>
      </li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Previous Versions"><img src="restfulspec_files/cleardot.gif" alt="Expand Previous Versions" class="tlw-control tlw-plus"></a><span class="tlw-title">Previous Versions</span></div><ul style="display: none;" id="1-sub-62">
        <li style="padding-top: 0pt; padding-bottom: 0pt;">
          <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Version 0.7"><img src="restfulspec_files/cleardot.gif" alt="Expand Version 0.7" class="tlw-control tlw-plus"></a><span class="tlw-title">Version 0.7</span></div><ul style="display: none;" id="1-sub-63">
            <li><a href="http://code.google.com/apis/opensocial/docs/0.7/devguide.html">Developer's Guide</a></li>
            <li><a href="http://code.google.com/apis/opensocial/docs/0.7/spec.html">API Specification</a></li>
            <li style="padding-top: 0pt; padding-bottom: 0pt;">
              <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand API Reference"><img src="restfulspec_files/cleardot.gif" alt="Expand API Reference" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/">API Reference</a></div><ul style="display: none;" id="1-sub-24">
                


<li style="padding-top: 0pt; padding-bottom: 0pt;">
  <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand opensocial"><img src="restfulspec_files/cleardot.gif" alt="Expand opensocial" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.html">opensocial</a></div><ul style="display: none;" id="1-sub-25">
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Activity"><img src="restfulspec_files/cleardot.gif" alt="Expand Activity" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Activity.html">Activity</a></div><ul style="display: none;" id="1-sub-26">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Activity.Field.html">Field</a></li>
        <li style="padding-top: 0pt; padding-bottom: 0pt;">
          <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand MediaItem"><img src="restfulspec_files/cleardot.gif" alt="Expand MediaItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Activity.MediaItem.html">MediaItem</a></div><ul style="display: none;" id="1-sub-27">
            <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Activity.MediaItem.Field.html">Field</a></li>
            <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Activity.MediaItem.Type.html">Type</a></li>
          </ul>
        </li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Address"><img src="restfulspec_files/cleardot.gif" alt="Expand Address" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Address.html">Address</a></div><ul style="display: none;" id="1-sub-28">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Address.Field.html">Field</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand BodyType"><img src="restfulspec_files/cleardot.gif" alt="Expand BodyType" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.BodyType.html">BodyType</a></div><ul style="display: none;" id="1-sub-29">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.BodyType.Field.html">Field</a></li>
      </ul>
    </li>
    <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Collection.html">Collection</a></li>
    <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.CreateActivityPriority.html">CreateActivityPriority</a></li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand DataRequest"><img src="restfulspec_files/cleardot.gif" alt="Expand DataRequest" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.html">DataRequest</a></div><ul style="display: none;" id="1-sub-30">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.FilterType.html">FilterType</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.Group.html">Group</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.PeopleRequestFields.html">PeopleRequestFields</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.PersonId.html">PersonId</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataRequest.SortOrder.html">SortOrder</a></li>
      </ul>
    </li>
    <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.DataResponse.html">DataResponse</a></li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Email"><img src="restfulspec_files/cleardot.gif" alt="Expand Email" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Email.html">Email</a></div><ul style="display: none;" id="1-sub-31">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Email.Field.html">Field</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Enum"><img src="restfulspec_files/cleardot.gif" alt="Expand Enum" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Enum.html">Enum</a></div><ul style="display: none;" id="1-sub-32">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Enum.Drinker.html">Drinker</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Enum.Gender.html">Gender</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Enum.Smoker.html">Smoker</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Environment"><img src="restfulspec_files/cleardot.gif" alt="Expand Environment" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Environment.html">Environment</a></div><ul style="display: none;" id="1-sub-33">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Environment.ObjectType.html">ObjectType</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Message"><img src="restfulspec_files/cleardot.gif" alt="Expand Message" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Message.html">Message</a></div><ul style="display: none;" id="1-sub-34">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Message.Field.html">Field</a></li>
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Message.Type.html">Type</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Name"><img src="restfulspec_files/cleardot.gif" alt="Expand Name" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Name.html">Name</a></div><ul style="display: none;" id="1-sub-35">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Name.Field.html">Field</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Organization"><img src="restfulspec_files/cleardot.gif" alt="Expand Organization" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Organization.html">Organization</a></div><ul style="display: none;" id="1-sub-36">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Organization.Field.html">Field</a></li>
      </ul>
    </li>
    <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Permission.html">Permission</a></li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Person"><img src="restfulspec_files/cleardot.gif" alt="Expand Person" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Person.html">Person</a></div><ul style="display: none;" id="1-sub-37">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Person.Field.html">Field</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Phone"><img src="restfulspec_files/cleardot.gif" alt="Expand Phone" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Phone.html">Phone</a></div><ul style="display: none;" id="1-sub-38">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Phone.Field.html">Field</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand ResponseItem"><img src="restfulspec_files/cleardot.gif" alt="Expand ResponseItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.ResponseItem.html">ResponseItem</a></div><ul style="display: none;" id="1-sub-39">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.ResponseItem.Error.html">Error</a></li>
      </ul>
    </li>
    <li style="padding-top: 0pt; padding-bottom: 0pt;">
      <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Url"><img src="restfulspec_files/cleardot.gif" alt="Expand Url" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Url.html">Url</a></div><ul style="display: none;" id="1-sub-40">
        <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/opensocial.Url.Field.html">Field</a></li>
      </ul>
    </li>
  </ul>
</li>

                  <li style="padding-top: 0pt; padding-bottom: 0pt;">
    <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand gadgets (core)"><img src="restfulspec_files/cleardot.gif" alt="Expand gadgets (core)" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets_core.html">gadgets (core)</a></div><ul style="display: none;" id="1-sub-41">
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.Prefs.html">Prefs</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand io"><img src="restfulspec_files/cleardot.gif" alt="Expand io" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.io.html">io</a></div><ul style="display: none;" id="1-sub-42">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.io.AuthorizationType.html">AuthorizationType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.io.ContentType.html">ContentType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.io.MethodType.html">MethodType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.io.RequestParameters.html">RequestParameters</a></li>
        </ul>
      </li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.json.html">json</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.util.html">util</a></li>
    </ul>
  </li>

                  <li style="padding-top: 0pt; padding-bottom: 0pt;">
    <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand gadgets (feature-specific)"><img src="restfulspec_files/cleardot.gif" alt="Expand gadgets (feature-specific)" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets_feature.html">gadgets (feature-specific)</a></div><ul style="display: none;" id="1-sub-43">
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.MiniMessage.html">MiniMessage</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.Tab.html">Tab</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.TabSet.html">TabSet</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.flash.html">flash</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.rpc.html">rpc</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand views"><img src="restfulspec_files/cleardot.gif" alt="Expand views" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.views.html">views</a></div><ul style="display: none;" id="1-sub-44">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.views.View.html">View</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.views.ViewType.html">ViewType</a></li>
        </ul>
      </li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand skins"><img src="restfulspec_files/cleardot.gif" alt="Expand skins" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.skins.html">skins</a></div><ul style="display: none;" id="1-sub-45">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.skins.Property.html">Property</a></li>
        </ul>
      </li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.7/reference/gadgets.window.html">window</a></li>
    </ul>
  </li>

              </ul>
            </li>
          </ul>
        </li>
        <li style="padding-top: 0pt; padding-bottom: 0pt;">
          <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Version 0.6"><img src="restfulspec_files/cleardot.gif" alt="Expand Version 0.6" class="tlw-control tlw-plus"></a><span class="tlw-title">Version 0.6</span></div><ul style="display: none;" id="1-sub-64">
            <li><a href="http://code.google.com/apis/opensocial/docs/0.6/devguide.html">Developer's Guide</a></li>
            <li><a href="http://code.google.com/apis/opensocial/docs/0.6/spec.html">API Specification</a></li>
            <li style="padding-top: 0pt; padding-bottom: 0pt;">
              
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand API Reference"><img src="restfulspec_files/cleardot.gif" alt="Expand API Reference" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/">API Reference</a></div><ul style="display: none;" id="1-sub-46">    
 <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand opensocial"><img src="restfulspec_files/cleardot.gif" alt="Expand opensocial" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.html">opensocial</a></div><ul style="display: none;" id="1-sub-47">
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Activity"><img src="restfulspec_files/cleardot.gif" alt="Expand Activity" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Activity.html">Activity</a></div><ul style="display: none;" id="1-sub-48">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Activity.Field.html">Field</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand MediaItem"><img src="restfulspec_files/cleardot.gif" alt="Expand MediaItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Activity.MediaItem.html">MediaItem</a></div><ul style="display: none;" id="1-sub-49">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Activity.MediaItem.Field.html">Field</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Activity.MediaItem.Type.html">Type</a>
  </li>
</ul>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Collection.html">Collection</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand ContentRequestParameters"><img src="restfulspec_files/cleardot.gif" alt="Expand ContentRequestParameters" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ContentRequestParameters.html">ContentRequestParameters</a></div><ul style="display: none;" id="1-sub-50">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ContentRequestParameters.AuthenticationType.html">AuthenticationType</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ContentRequestParameters.ContentType.html">ContentType</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ContentRequestParameters.MethodType.html">MethodType</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.CreateActivityPriority.html">CreateActivityPriority</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand DataRequest"><img src="restfulspec_files/cleardot.gif" alt="Expand DataRequest" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.html">DataRequest</a></div><ul style="display: none;" id="1-sub-51">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.ActivityRequestFields.html">ActivityRequestFields</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.FilterType.html">FilterType</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.Group.html">Group</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.PeopleRequestFields.html">PeopleRequestFields</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.PersonId.html">PersonId</a>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataRequest.SortOrder.html">SortOrder</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.DataResponse.html">DataResponse</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Environment"><img src="restfulspec_files/cleardot.gif" alt="Expand Environment" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Environment.html">Environment</a></div><ul style="display: none;" id="1-sub-52">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Environment.ObjectType.html">ObjectType</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Permission.html">Permission</a>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Person"><img src="restfulspec_files/cleardot.gif" alt="Expand Person" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Person.html">Person</a></div><ul style="display: none;" id="1-sub-53">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Person.Field.html">Field</a>
  </li>
</ul>
  </li>
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand ResponseItem"><img src="restfulspec_files/cleardot.gif" alt="Expand ResponseItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ResponseItem.html">ResponseItem</a></div><ul style="display: none;" id="1-sub-54">
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.ResponseItem.Error.html">Error</a>
  </li>
</ul>
  </li>
  <li><a href="http://code.google.com/apis/opensocial/docs/0.6/reference/opensocial.Surface.html">Surface</a>
  </li>
</ul>
</li>

</ul>


            </li>
          </ul>
        </li>
          <li style="padding-top: 0pt; padding-bottom: 0pt;">
            <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Version 0.5"><img src="restfulspec_files/cleardot.gif" alt="Expand Version 0.5" class="tlw-control tlw-plus"></a><span class="tlw-title">Version 0.5</span></div><ul style="display: none;" id="1-sub-65">
              <li><a href="http://code.google.com/apis/opensocial/docs/0.5/devguide.html">Developer's Guide</a></li>
              <li style="padding-top: 0pt; padding-bottom: 0pt;">
                
<div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand API Reference"><img src="restfulspec_files/cleardot.gif" alt="Expand API Reference" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/">API Reference</a></div><ul style="display: none;" id="1-sub-55">
  <li style="padding-top: 0pt; padding-bottom: 0pt;">
    <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand opensocial"><img src="restfulspec_files/cleardot.gif" alt="Expand opensocial" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.html">opensocial</a></div><ul style="display: none;" id="1-sub-56">
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Activity"><img src="restfulspec_files/cleardot.gif" alt="Expand Activity" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Activity.html">Activity</a></div><ul style="display: none;" id="1-sub-57">
	        <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Activity.Field.html">Field</a></li>
	        <li style="padding-top: 0pt; padding-bottom: 0pt;">
	          <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand MediaItem"><img src="restfulspec_files/cleardot.gif" alt="Expand MediaItem" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Activity.MediaItem.html">MediaItem</a></div><ul style="display: none;" id="1-sub-58">
              <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Activity.MediaItem.Field.html">Field</a></li>
              <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Activity.MediaItem.Type.html">Type</a></li>
            </ul> 
          </li> <!-- end MediaItem -->
        </ul>
      </li> <!-- end Activity -->
      <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Collection.html">Collection</a></li>
      <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.CreateActivityPriority.html">CreateActivityPriority</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand DataRequest"><img src="restfulspec_files/cleardot.gif" alt="Expand DataRequest" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.html">DataRequest</a></div><ul style="display: none;" id="1-sub-59">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.ActivityRequestFields.html">ActivityRequestFields</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.FilterType.html">FilterType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.Group.html">Group</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.PeopleRequestFields.html">PeopleRequestFields</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.PersonId.html">PersonId</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.ProfileDetailType.html">ProfileDetailType</a></li>
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataRequest.SortOrder.html">SortOrder</a></li>
        </ul> 
      </li> <!-- End DataRequest -->
      <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.DataResponse.html">DataResponse</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Person"><img src="restfulspec_files/cleardot.gif" alt="Expand Person" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Person.html">Person</a></div><ul style="display: none;" id="1-sub-60">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Person.Field.html">Field</a></li>
        </ul>
      </li> <!-- end Person -->
      <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.ResponseItem.html">ResponseItem</a></li>
      <li style="padding-top: 0pt; padding-bottom: 0pt;">
        <div class="tlw-title tlw-branch"><a href="javascript:void(0)" class="tlw-control" title="Expand Stream"><img src="restfulspec_files/cleardot.gif" alt="Expand Stream" class="tlw-control tlw-plus"></a><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Stream.html">Stream</a></div><ul style="display: none;" id="1-sub-61">
          <li><a href="http://code.google.com/apis/opensocial/docs/0.5/reference/opensocial.Stream.Field.html">Field</a></li>
        </ul>
      </li> <!-- end Stream -->
    </ul>
  </li> <!-- end opensocial -->
</ul>


              </li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li><h1 class="tlw-ignore">RESTful API</h1>
    <ul>
      <li class="selected"><a href="http://code.google.com/apis/opensocial/docs/0.8/restfulspec.html">RESTful API Specification</a></li>
    </ul>
  </li>
  <li><h1 class="tlw-ignore">Other Resources</h1>
    <ul>
      <li><a href="http://code.google.com/apis/orkut/">Build apps for Orkut</a></li>
      <li><a href="http://code.google.com/apis/gadgets/docs/spec.html">Gadgets Specification</a></li>
    </ul>
  </li>
</ul>

        <a class="hidden" href="#gc-topnav-anchor">More OpenSocial resource links</a>
      </div>
      
      <div style="position: relative;" class="g-unit" id="gc-pagecontent"><ol class="cs-breadcrumbs"><li class="cs-crumb"><a href="http://code.google.com/apis/opensocial/docs/index.html" class="" title="Official OpenSocial documentation">Docs</a><span class="cs-crumbSpacer">&nbsp;&gt;&nbsp;</span></li><li class="cs-crumb"><a href="http://code.google.com/apis/opensocial/docs/0.8/restfulspec.html">RESTful API Specification</a></li></ol>
        <h1 class="page_title">RESTful API Specification</h1>


<h4>Revision 1031 5/27/2008</h4>
<p></p><p>
</p><p>The RESTful API serves as a common protocol understood by all
OpenSocial 0.8-compliant clients and servers. It replaces the November
2007 OpenSocial Data API proposal (which was based on the Google Data
APIs).
</p>
<h3>0. Notation and Conventions</h3>

<p>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in <a href="http://tools.ietf.org/html/rfc2119">[RFC2119]</a>. Domain name examples use <a href="http://tools.ietf.org/html/rfc2606">[RFC2606]</a>.
</p>
<h3>1. Overview</h3>

<p>This API defines a language- and platform- neutral protocol for clients to interact with <a href="http://code.google.com/apis/opensocial/">OpenSocial</a> <a href="http://code.google.com/apis/opensocial/container.html">container servers</a>
outside of gadgets on a web page. As a protocol, it is intended to be
reasonably easy to implement in any language and on any platform. It
should also be usable across a range of clients, from gadgets operating
within a web page to servers communicating to synchronize data about a
user.
</p>
<p>The protocol operates primarily in terms of resources and operations
on them. It is defined on top of the HTTP protocol, and uses the
standard HTTP methods (GET, POST, PUT, DELETE, etc.) to retrieve and
change server state.
</p>
<p>No single data representation is ideal for every client. This
protocol defines dual representations for each resource in two widely
supported formats, JSON <a href="http://www.ietf.org/rfc/rfc.txt">[RFC4627]</a> and Atom/AtomPub <a href="http://www.rfc-editor.org/rfc/rfc4287.txt">[RFC4287]</a><a href="http://www.rfc-editor.org/rfc/rfc5023.txt">[RFC5023]</a>,
using a set of generic mapping rules. The mapping rules allow a server
to write to a single interface rather than implementing the protocol
twice.
</p>
<p>OpenSocial container servers are free to define additional
representations but MUST support at least the JSON and Atom formats
defined in this document.
</p>
<p>The protocol defines Activity, Person, Group, and AppData resources
and collections (resources which consist of a set of other resources).
Most operations consist of retrieving (GET), updating (PUT), creating
(POST or PUT), or destroying (DELETE) these resources. The protocol
provides an optional feature to batch multiple requests together in a
pipeline to avoid multiple HTTP round trips. Finally, it specifies an
optional partial update feature which avoids sending large resources
over the wire to update just one field.
</p>
<p><a href="http://code.google.com/apis/opensocial/docs/0.8/spec.html#background">OpenSocial API Background</a> details the underlying concepts used below; this document assumes familiarity with the OpenSocial model.
</p>
<h3>2. Data Representations</h3>

<p>Each resource has a two representations, as JSON and Atom (XML). All
data must be representable in both formats, but we do not attempt to
map from generic XML or Atom to JSON. Instead, we define an internal
data model using English and JSON syntax, and then define the mappings
between this and Atom/JSON.
</p>
<p>Each resource is represented as a hierarchical tree of elements.
Ordering of elements within a parent element may or may not be
significant, depending on the context. Mapping consists of converting
between the internal hierarchy and the JSON / Atom protocol format.
</p>
<p>The set of allowed fields in each type of data is the same as the
set documented in the OpenSocial 0.8 API reference. The standard sets
of fields are the same between the RESTful API and the JS APIs.
</p>
<p>The general rules for mapping between the Atom and JSON formats are
as follows. Each data type may add additional aliasing rules.
</p><ul>
  <li> The default location for all data in the Atom format
is in atom:entry/atom:content/datatype, where datatype is a root node
naming the type of data delivered: &lt;person&gt;, &lt;group&gt;,
&lt;activity&gt;, or &lt;appdata&gt;. </li><li>
The field names are the same as in the <a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial">JS documentation</a>, in camelCase (the same format as the JS field accessors; e.g, "lastName".
  </li><li>
Strings are represented as strings in both formats.
  </li><li>
Dates and timestamps are represented as strings containing AtomPub (RFC3339) format date-time elements; see <a href="http://atompub.org/rfc4287.html#date.constructs">section 3.3 of [RFC4287]</a>.
These are also known as "XSD Dates". In cases where only a
day-of-the-year is desired, e.g., a birthday, the year SHOULD be
specified as 0000. </li><li>Enums are represented as objects with "displayvalue" (localizable, customizable string) and "key" (key) fields.
  </li><li>Arrays are represented as arrays in the JSON representation and as repeated fields in the XML representation.
  </li><li>Sub-objects are represented as sub-elements in both formats.
  </li><li>Fields
are placed directly in the root object in the JSON format. In the Atom
format, they are by default placed under atom:content/datatype (e.g.,
atom:content/person for person data). Some fields are 'hoisted' and
aliased to standard Atom fields directly underneath atom:entry. There
are three standard aliases that apply to all data types: <ul>
      <li>atom:entry/atom:id aliases the "id" field. The JSON format id is the <a href="http://code.google.com/apis/opensocial/docs/0.8/spec.html#people">OpenSocial globally unique ID</a>,
which consists of the container domain (e.g., example.org), a colon,
and an alphanumeric string but with the container domain prepended. For
example, example.org:78gh37261ddfdf. In the Atom format, it is
translated into the required URI data type by prepending "urn:guid:" to
the OpenSocial ID string. These rules are intended to make mapping IDs
between the RESTful API and the JS API straightforward while preserving
global uniqueness. </li><li>atom:entry/atom:updated aliases the JSON field
indicating the most recent update time if available (POSTED_TIME for
Activity), or the generation time if no better information is
available. </li><li>atom:entry/atom:published aliases the JSON field indicating creation time (POSTED_TIME for Activity).
    </li></ul>
  </li></ul>

<p>Examples of the primary types of data follow. Each example shows
both representations, JSON and Atom, with the payload data highlighted
for ease of comparison.
</p>
<h4>2.1 Collections</h4>

<p>Collections are a useful abstraction for dealing generically with
multiple things, whether those things are persons, groups, activities,
or application data sets. They have both Atom and JSON representations;
the Atom representation is simply a standard Atom feed whose entries
are one of the entry types specified above. The default JSON collection
representation is a JSON object containing an "entry" slot containing a
list of JSON objects. Collections use the <a href="http://www.opensearch.org/Home">OpenSearch conventions</a> for reporting totalResults (for complete unpaged feed), startIndex of current page, and itemsPerPage.
</p>
<p>For example:
</p>
<p>application/json representation:
</p><pre>{
   "author" : "example.org:58UIDCSIOP233FDKK3HD44",
   "link" : {"rel" : "next", "href" : "http://api.example.org/..." },
   "totalResults" : 100,
   "startIndex" : 1
   "itemsPerPage" : 10
   "entry" : [
      {...first thingie...},
      {...second thingie...}
      ...
   ]
}
</pre>
<p>application/atom+xml representation:
</p><pre>&lt;feed xmlns="http://www.w3.org/2005/Atom" xmlos:osearch="http://a9.com/-/spec/opensearch/1.1"&gt;
  &lt;author&gt;&lt;uri&gt;urn:guid:example.org:58UIDCSIOP233FDKK3HD44&lt;/uri&gt;&lt;/author&gt;
  &lt;link rel="next" href="http://api.example.org/..." /&gt;
  &lt;osearch:totalResults&gt;100&lt;/osearch:totalResults&gt;
  &lt;osearch:startIndex&gt;1&lt;/osearch:startIndex&gt;
  &lt;osearch:itemsPerPage&gt;10&lt;/osearch:itemsPerPage&gt;
  &lt;entry&gt;...first thingie...&lt;/entry&gt;
  &lt;entry&gt;...second thingie...&lt;/entry&gt;
  ...
&lt;/feed&gt;
</pre>
<p>Note: The standard "next" link in each case allows for paginated
collections without the need to support full random access; collections
MAY also support randomly accessed pages via query parameters.
</p>
<p>Activity stream collections are ordered chronologically by default,
most recent activities first; containers MAY by default order other
collections arbitrarily. Other orderings can be requested for
collections using query parameters.
</p>
<h4>2.2 Person</h4>

<p>A Person contains a social network oriented data about a single
person. The same record is used for contacts/friends and for profiles.
</p>
<p>See the <a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Person.Field">Person Fields API doc</a> for a full list of available fields and their (JS) types. See also the general mapping rules in section 2.
</p><p>A minimal Person example:
</p>
<p>application/json representation:
</p><pre>{
  "id" : "example.org:34KJDCSKJN2HHF0DW20394",
  "name" : {"unstructured" : "Jane Doe"},
  "gender" : {"displayvalue" : "女性", "key" : "FEMALE"}
}
</pre>
<p>application/atom+xml representation:
</p><pre>&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;
  &lt;content type="application/xml"&gt;
    &lt;person xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
      &lt;name&gt;
        &lt;unstructured&gt;Jane Doe&lt;/unstructured&gt;
      &lt;/name&gt;
      &lt;gender key="FEMALE"&gt;女性&lt;/gender&gt;
    &lt;/person&gt;
  &lt;/content&gt;
  &lt;title/&gt;
  &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
  &lt;author/&gt;
  &lt;id&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/id&gt;
&lt;/entry&gt;
</pre>
<p>Note: In general clients can ask for a full representation of a
resource, with all fields and sub-fields, or a partial representation,
using query parameters; see below for details.
</p>
<p>Note: The atom:summary element is the appropriate place to put a
text or HTML representation of the structured data present in the
content element, and the atom:title element is the appropriate place to
copy a short descriptive name for the entry, such as name.unstructured.
Servers MAY choose to add these or other fields to make their feeds
more useful for generic aggregators or tools.
</p>
<h4>2.3 Group</h4>
<p>OpenSocial Groups are owned by people, and are used to tag or
categorize people and their relationships. The RESTful API supports
querying for the available groups for a given user. The groups are
returned as a collection. Each group has a display name, an identifier
which is unique within the groups owned by that person, and a URI link.
</p>
<p>A Group example:
</p><pre><p>application/json representation:
</p>{
  "id" : "example.org:34KJDCSKJN2HHF0DW20394/friends",
  "title" : "Peeps",
  "link" : {rel : "alternate", "href" : "http://api.example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends" }
}
</pre>
<p>application/atom+xml representation:
</p><pre>&lt;entry xmlns="http://www.w3.org/2005/Atom&gt;
  &lt;link rel="alternate" href="http://api.example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends" /&gt;
  &lt;title&gt;Peeps&lt;/title&gt;
  &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
  &lt;id&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394/friends&lt;/id&gt;
&lt;/entry&gt;
</pre>
<p>Groups only appear within Group Collections and are used to retrieve a list of available groups for a given person.
</p>
<h4>2.4 Activity</h4>
<p>An OpenSocial Activity represents a short summary or notification of
a timestamped event, often with pointers for more information.
</p>
<p>See the <a href="http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Activity.Field">Activity Fields API doc</a>
for a full list of available fields and their (JS) types. Activities
have extensive hoisting rules to ensure maximum compatibility with
standard feed processing code:
</p><ul><li>atom:entry/atom:title aliases "title"
</li><li>atom:entry/atom:summary aliases "body"
</li><li>atom:entry/atom:link@rel="self" aliases "url"
</li><li>atom:entry/atom:icon aliases "faviconUrl"
</li><li>atom:entry/atom:source/atom:title aliases "streamTitle"
</li><li>atom:entry/atom:source/atom:link@rel="self" aliases "streamUrl"
</li><li>atom:entry/atom:generator/atom:uri aliases "appId"
</li><li>atom:entry/atom:author/atom:uri aliases "userId"
</li></ul>
<p>A minimal Activity example:
</p>
<p>application/json representation:
</p><pre>{
  "id" : "http://example.org/activities/example.org:87ead8dead6beef/self/af3778",
  "title" : { "type" : "html",
              "value" : "&lt;a href=\"foo\"&gt;some activity&lt;/a&gt;"
            }
  "updated" : "2008-02-20T23:35:37.266Z",
  "body" : "Some details for some activity",
  "bodyId" : "383777272"
  "url" : "http://api.example.org/activity/feeds/.../af3778"
  "userId" : "example.org:34KJDCSKJN2HHF0DW20394"
}
</pre>
<p> application/atom+xml representation:
</p><pre>&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;
  &lt;category term="status"/&gt;
  &lt;id&gt;http://example.org/activities/example.org:87ead8dead6beef/self/af3778&lt;/id&gt;
  &lt;title type="html"&gt;&lt;a href="foo"&gt;some activity&lt;/a&gt;&lt;/title&gt;
  &lt;summary&gt;Some details for some activity&lt;/summary&gt;
  &lt;updated&gt;2008-02-20T23:35:37.266Z&lt;/updated&gt;
  &lt;link rel="self" type="application/atom+xml" href="http://api.example.org/activity/feeds/.../af3778"/&gt;
  &lt;author&gt;&lt;uri&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/uri&gt;&lt;/author&gt;
  &lt;content&gt;
    &lt;activity xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
      &lt;body_id&gt;383777272&lt;/bodyId&gt;
    &lt;activity&gt;
  &lt;/content&gt;
&lt;/entry&gt;
</pre>
<h4>2.5 AppData</h4>
<p>AppData stores uninterpreted key/value pairs on behalf of an
application. The standard unit of AppData is all of the key/value pairs
stored for a given app on behalf of a given user; however, the API
supports other types of queries (detailed below). To retrieve a subset
of fields, use the fields= selector syntax (detailed below).
</p>
<p>An isolated AppData example
</p>
<p>The first example is of a collection of key/value pairs for a particular application/user pair:
</p>
<pre><p>application/json representation:
</p>{
  "pokes" : 3,
  "last_poke" : "2008-02-13T18:30:02Z"
}
</pre>
<p>application/atom+xml representation:
</p><pre>&lt;entry xmlns="http://www.w3.org/2005/Atom&gt;
  &lt;content type="text/xml"&gt;
    &lt;appdata xmlns="http://opensocial.org/2008/opensocial"&gt;  
        &lt;pokes&gt;3&lt;/poke&gt;
        &lt;last_poke&gt;2008-02-13T18:30:02Z&lt;/last_poke&gt;
      &lt;/appdata&gt;
  &lt;/content&gt;
  &lt;title/&gt;
  &lt;updated&gt;2003-12-13T18:30:02Z&lt;/updated&gt;
  &lt;author&gt;&lt;url&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/url&gt;&lt;/author&gt;
  &lt;id&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/id&gt;
&lt;/entry&gt;
</pre>
<p>An AppData Collection Example
</p>
<p>In this example, a client has requested a collection of data that
spans multiple users. The result is a collection which, by default, is
given a special default JSON representation as a mapping from users to
their data. It's also possible to get a generic representation as an
array using a query parameter:
</p>
<p>application/json default array representation:
</p><pre>{
  "entry" :
    [
       { "id" : "example.org:34KJDCSKJN2HHF0DW20394", "pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" },
       { "id" : "example.org:58UIDCSIOP233FDKK3HD44", "pokes" : 2, "last_poke" : "2007-12-16T18:30:02Z" }
    ]
}
</pre>
<p>application/json representation (with indexBy=id):
</p><pre>{
  "entry" : {
    "example.org:34KJDCSKJN2HHF0DW20394" : {"pokes" : 3, "last_poke" : "2008-02-13T18:30:02Z" },
    "example.org:58UIDCSIOP233FDKK3HD44" : {"pokes" : 2, "last_poke" : "2007-12-16T18:30:02Z" }
  }
}
<p>application/atom+xml representation:
</p>&lt;feed xmlns="http://www.w3.org/2005/Atom&gt;
  &lt;id&gt;...&lt;/id&gt;
  &lt;title&gt;...&lt;/title&gt;
  &lt;entry&gt;
    &lt;content type="text/xml"&gt;
      &lt;appdata&gt;
        &lt;pokes&gt;3&lt;/poke&gt;
        &lt;last_poke&gt;"2008-02-13T18:30:02Z"&lt;/last_poke&gt;
      &lt;/appdata&gt;
    &lt;/content&gt;
    &lt;title/&gt;
    &lt;updated&gt;2008-02-13T18:30:02Z&lt;/updated&gt;
    &lt;author&gt;&lt;url&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/url&gt;&lt;/author&gt;
    &lt;id&gt;urn:guid:example.org:34KJDCSKJN2HHF0DW20394&lt;/id&gt;
  &lt;/entry&gt;
  &lt;entry&gt;
    &lt;content type="text/xml"&gt;
      &lt;appdata&gt;
        &lt;pokes&gt;2&lt;/poke&gt;
        &lt;last_poke&gt;"2007-12-16T18:30:02Z"&lt;/last_poke&gt;
      &lt;/appdata&gt;
    &lt;/content&gt;
    &lt;title/&gt;
    &lt;updated&gt;2007-12-16T18:30:02Z&lt;/updated&gt;
    &lt;author&gt;&lt;url&gt;uurn:guid:example.org:58UIDCSIOP233FDKK3HD44&lt;/url&gt;&lt;/author&gt;
    &lt;id&gt;urn:guid:example.org:58UIDCSIOP233FDKK3HD44&lt;/id&gt;  
  &lt;/entry&gt;
&lt;/entry&gt;
</pre>
<p>The default representation of a collection is simply a JSON list of
records ([ {...}, {....}, ...]). The special type "index" means that
the collection is instead to be represented as a mapping, using the
index field; this is requested by supplying a query parameter "indexBy"
(see below).
</p>
<p>The data within each field is assumed to be in JSON format and is otherwise uninterpreted.
</p>
<h3>3. Operations</h3>

<p>OpenSocial uses standard HTTP methods: GET to retrieve, PUT to
update in place, POST to create new, and DELETE to remove. POST is
special; it operates on collections and creates new activities,
persons, or app data within those collections, and returns the base URI
for the created resource in the Location: header, per AtomPub
semantics.
</p>
<p>Restricted clients, or clients behind restricted clients, which
cannot use PUT or DELETE SHOULD translate PUT and DELETE to POST
operations with an additional X-HTTP-Method-Override: header:
</p>
<pre>    POST /... HTTP/1.1
    ...
    X-HTTP-Method-Override: PUT
</pre>
<p>Servers SHOULD respond to POST+X-HTTP-Method-Override as if the content of the header were the actual operation sent.
</p>
<p>Note: OpenSocial 0.8 does not support cross-domain JSONP (GET with
callback), but servers MAY offer this as an extension. It is
RECOMMENDED that such servers implement appropriate security and
authorization controls.
</p>
<h3>4. Request Authentication and Authorization Context</h3>

<p>Each RESTful operation has a request context that usually includes
authentication and authorization information. Typically, the context
information includes the requestor id (the user initiating the request)
and app ID (the application, or whatever is acting as the user's
agent). It may include other container-specific information.
</p>
<p>Containers MUST be an <a href="http://oauth.net/core/1.0/">OAuth Core 1.0</a>
Service Provider (a web application that allows access via OAuth).
Containers MAY also support other ways to establish a request context.
Containers MUST also support the <a href="http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html">Consumer Request OAuth extension</a>,
in which the end user has not directly authorized the operation.
Applications SHOULD ensure that the users have given prior consent,
implicitly or explicitly, to the operation or class of operations.
However, containers MAY require an additional prior trust relationship
be established by the app in order to allow use of Consumer Request
OAuth.
</p>
<p>If a Consumer has a user identifier and wishes to indicate that the
operation is being done on behalf of that particular user, it SHOULD
provide the OAuth extension parameter xoauth_requestor_id with the
OAuth signed parameters. Consumers SHOULD only provide this if the user
has given prior consent, implicitly or explicitly, to the operation or
class of operations, as it indicates that the operation is being done
on behalf of the user. Container SPs MUST either honor the parameter or
ignore it as if it were not provided.
</p>
<p>Thus, a request context usually includes the requesting application
(the OAuth Consumer), and may include the requesting user, either
implicitly via an oauth_token or explicitly via xoauth_requestor_id. It
may also include additional information via extensions or other
channels (cookies, URI parameters, client SSL certificates, etc.) A
container may also accept requests with no authentication or
authorization (authnz) information at all for public data. A container
may provide a public version (e.g., of a profile) if no authnz
information is provided.
</p>
<p>Note that the data provided for a given RESTful URI MAY vary per
requestor or app. Thus, the meaning of the resource at a given URI is
"the view of the information available to the current requestor/app
combination". In the case where no information is available due to lack
of authorization, an HTTP 401 Unauthorized response SHOULD be returned
to the client. In the case where at least some view of the information
is available, it SHOULD be returned using a 200 status, with a standard
OAuth WWW-Authenticate: header indicating that additional information
may be available when using a different authnz context.
</p>
<h3>5. Discovery</h3>

<p>A container declares what collection and features it supports, and
provides templates for discovering them, via a simple discovery
document. A client starts the discovery process at the container's
identifier URI (e.g., example.org). The full flow is available at <a href="http://xrds-simple.net/core/1.0/">http://xrds-simple.net/core/1.0/</a>; in a nutshell:
</p><ol>
<li>Client GETs {container-url} with Accept: application/xrds+xml
</li><li>Container responds with either an X-XRDS-Location: header pointing to the discovery document, or the document itself.
</li><li>If the client received an X-XRDS-Location: header, follow it to get the discovery document.
</li></ol>
<p>The discovery document is an XML file in the same format used for
OpenID and OAuth discovery, defined at
http://xrds-simple.net/core/1.0/:
</p><pre>&lt;XRDS xmlns="xri://$xrds"&gt;
    &lt;XRD xmlns:simple="http://xrds-simple.net/core/1.0" xmlns="xri://$XRD*($v*2.0)" xmlns:os="http://ns.opensocial.org/" version="2.0"&gt;
        &lt;Type&gt;xri://$xrds*simple&lt;/Type&gt;
        &lt;Service&gt;
          &lt;Type&gt;http://ns.opensocial.org/people/0.8&lt;/Type&gt;
          &lt;os:URI-Template&gt;http://api.example.org/people/{guid}/{selector}{-prefix|/|pid}&lt;/URI-Template&gt;
        &lt;/Service&gt;
        &lt;Service&gt;
          &lt;Type&gt;http://ns.opensocial.org/activities/0.8&lt;/Type&gt;
          &lt;os:URI-Template&gt;http://api.example.org/activities/{guid}/{selector}&lt;/URI-Template&gt;
        &lt;/Service&gt;
        &lt;Service&gt;
          &lt;Type&gt;http://ns.opensocial.org/appdata/0.8&lt;/Type&gt;
          &lt;os:URI-Template&gt;http://api.example.org/appdata/{guid}/{selector}&lt;/URI-Template&gt;
        &lt;/Service&gt;
    &lt;/XRD&gt;
&lt;/XRDS&gt;
</pre>
<p>Each Service advertises a service provided by the container. Each
container MUST support the service Types documented below and MAY
support others by advertising them in the discovery document. Each
service comprises a set of resources defined by the given URI Template
(or URI, if there is only a single resource). Clients follow the URIs
and instantiate the templates to find and operate on specific
resources. (URI Template syntax is documented at
http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-03.txt.)
</p>
<p>The set of substitution variables is fixed for each service Type.
The core set of service Types and their substitution variables is
documented below. Extensions to OpenSocial SHOULD document their
substitution variables; note that a reasonable place to put human
readable documentation is at the namespace URI.
</p>
<h3>6. The Core OpenSocial Service Types</h3>

<p>This section defines the core types that every OpenSocial container
MUST support, their XRDS types, and their semantics. Unless otherwise
specified, all HTTP operations are generally allowed for any URI
endpoint; a container which wishes to specify the allowed operations
SHOULD provide an HTTP Allow: header for each resource listing the
allowed operations.
</p>
<h4>6.1 People</h4> 

<p>XRDS Type: http://ns.opensocial.org/people/0.8
</p>guid : Container-globally-unique user identifier; identifies owner
of the people data, or @me to indicate the requestor should be used
selector : One of
<ul>
<li>A user-defined local group name to select a group of contacts (a collection)
</li><li>@self to select the person record for guid
</li><li>@all to select all the universal set of contacts (a collection)
</li><li>@friends to select the subset of contacts which are friends (a collection)
</li></ul>pid : In the context of a collection selector, picks a single
person record from that collection. The pid value MAY be relative to
that collection.
<pre>People URI examples:
  /people/{guid}/@all                      -- Collection of all people connected to user {guid}
  /people/{guid}/@friends                  -- Collection of all friends of user {guid}; subset of        @all
  /people/{guid}/{groupid}                 -- Collection of all people connected to user {guid} in group {groupid}
  /people/{guid}/@all/{pid}                -- Individual person record for a specific person known to {guid}; shows {guid}'s view of {pid}.
  /people/{guid}/@self                     -- Profile record for user {guid}
  /people/@me/@self                        -- Profile record for requestor
</pre>
<p>Note that a given container may use alternative URI formats; for example,
</p><pre>  /people.cgi?guid={guid}&amp;groupid={groupid}
</pre>
<p>is a valid URI pattern given the appropriate XRDS discovery document
which allows clients to map the parameters to a concrete URI.
</p>
<p>Friends may be added by POSTing to the appropriate collection (e.g.,
/people/{guid}/@friends). Containers MAY require a dual opt-in process
before the friend record appears in the collection, and in this case
SHOULD return a 202 Accepted response, indicating that the request is
'in flight' and may or may not be ultimately successful. </p>
<h4>6.2 Groups</h4> 

<p>XRDS Type: http://ns.opensocial.org/groups/0.8
</p>
<p>guid : Container-globally-unique user identifier; identifies owner
of the people data; can be @me to indicate auth[nz] requestor should be
used.
</p>
Groups URI examples:
<pre>  /groups/{guid}                      -- Collection of groups associated with user {guid}
</pre>
<h4>6.3 Activities</h4> 

<p>XRDS Type: http://ns.opensocial.org/activities/0.8
</p>
<p>guid : Container-globally-unique user identifier; owner or recipient
of the activity data, or @me to indicate the requestor should be used
</p>selector : One of
<ul><li>A user-defined local group name to select activities from people in the group (a collection)
</li><li>@self to select the activities for user guid (a collection)
</li><li>@friends to select the activities from friends only (a collection)
</li></ul>

<p>Activity URI examples:
</p><pre>/activities/{guid}/@self            -- Collection of activities generated by given user
/activities/{guid}/@friends             -- Collection of activities for friends of the given user {guid}
/activities/{guid}/{groupid}            -- Collection of activities for people in group {groupid} belonging to given user {uid}
/activities/{guid}/@self/{activityid}   -- Individual activity resource; usually discovered from collection
</pre>
<h4>6.4 AppData (http://ns.opensocial.org/appdata/0.8)</h4>

<p>guid : Container-globally-unique user identifier, or @me to indicate the requestor should be used
</p>selector : One of
<ul><li>A user-defined local group name to select appdata from people in the group (a collection)
</li><li>@self to select the appdata for user guid only (a collection)
</li><li>@friends to select the appdata from friends of guid only (a collection)
</li></ul>


<p>AppData URI examples:
</p><pre>/appdata/{guid}/@self/{appid}              -- All app data for user {guid}, app {appid}
/appdata/{guid}/@friends/{appid}           -- All app data for friends of user {guid} and app {appid}; read-only (only GET and HEAD supported)
/appdata/{guid}/@self/{appid}?fields=count -- Just the count field for user {guid}, app {appid}
</pre>
<h4>6.5 Standard Query Parameters</h4>

<p>These additional query parameters may be used with any URI above.
The parameters startIndex and count are interpreted according to the <a href="http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax">OpenSearch</a> spec.
</p><pre>format={format}                    -- Format desired; one of (atom, json); default is json if not provided
fields={-join|,|field}             -- List of fields to include in representation or in the members of a collection. Default is to include all available fields.  
startIndex={startIndex}            -- Index into a paged collection  
count={count}                      -- Requests page size for paged collection
networkDistance={networkDistance}  -- Modifies group-relative requests (@friends, etc.) to include the transitive closure of all friends up to {networkDistance} links away.  May not be honored by the container.
indexBy={fieldname}                -- For a collection, return a JSON mapping which uses the named field (must be unique key) to the rest of the fields.
orderBy={fieldname}                -- For a collection, return entries sorted by the given field.  
</pre> 


<h3>7. Security Considerations</h3>
<p>Containers SHOULD carefully consider security. Containers MUST
support OAuth but SHOULD use appropriate policies to determine allowed
operations on a per-Consumer and per-user basis. Per the OAuth spec,
Containers SHOULD document how a Consumer can direct a user to a
Container web page to obtain an oauth_token for future use. Note that
this is a vector for phishing if the user is required to enter their
credentials.
</p>
<p>Containers SHOULD support SSL connections for sensitive data as
OAuth on its own does not provide encryption or message body integrity
checking. Containers should base their security decisions on the type
of client in use; a generally available desktop client, for example,
cannot effectively protect a Consumer Secret that is installed with
each client. The security of communications with a partner service, on
the other hand, is dependent on the effectiveness of that service's
security procedures. Containers may wish to rate limit requests from
unknown clients, or require registration, in order to mitigate risk. </p>
<p>Containers should scope oauth_tokens as narrowly as possible (e.g.,
allow reading but not writing if a client only performs reads). </p>
<h3>8. Concurrency Control (Optional)</h3>

<p>This feature allows a container and client to cooperate in order to
prevent multiple containers from overwriting each other's data. It uses
the standard HTTP/AtomPub optimistic concurrency mechanism based on
ETags (see section 9.5 of <a href="http://www.rfc-editor.org/rfc/rfc5023.txt">[RFC5023]</a> for details; the same mechanism applies regardless of the data format used for the body of the PUT). 
</p>
<h4>8.1 Discovery</h4>

<p>Concurrency control is available on a resource-by-resource basis.
When an updateable resource supports concurrency control, the container
SHOULD supply an ETag encoding the resource's current state when
supplying a representation to clients. If a resource does not support
optimistic concurrency, it MUST respond to an update request containing
an If-Match: header with a 403 Not Implemented error.
</p>
<p>A server which chooses not to support optimistic concurrency SHOULD
omit ETags on its responses for updateable resources. A client SHOULD
assume that optimistic concurrency is not available if no ETag is
present. </p>
<h4>8.2 Semantics</h4>

<p>When a client is given an ETag, it MAY supply that ETag in an
If-Match: header on subsequent updates. The semantics are that the
client can supply the new representation and the previous ETag; the
server inspects the current state of the resource and applies the
update if the client supplied ETag matches (meaning no intervening
updates have happened), otherwise responds with a 409 Conflict error
and the new ETag. Clients may then take appropriate actions to resolve
the conflict, or fail the operation, depending on their needs. Clients
are also free to use PUT to simply overwrite a resource with a new
state at any time, ignoring possible overwriting problems.
</p>
<p>If partial updates are supported (see below), a server MUST accept
an ETag given for either a base resource or a projection of that
resource upon a subsequent PUT for that resource. That is, it is legal
to supply an ETag you received when GETting the full representation of
a resource even if you are only PUTting back a single field. If you
intend to simply overwrite that single field, then you skip sending any
ETag.
</p>
<h3>9. Batching (Optional)</h3>

<p>There are use cases where clients want to send several operations,
in a specified sequence, to a server to execute in turn, but do not
want to incur the overhead of multiple HTTP round trips. A specific use
case is a gadget which first adds a new friend, then retrieves the 5th
page of friends (what it's currently viewing). These are two ad hoc
requests from the point of view of the server involved, but for
optimization purposes the gadget wants to batch up the requests and
responses to minimize latency. It is also possible that the requests
and responses would be to different types of data (activities, people,
or persistence) and/or to different servers. In the most general case
it is useful to be able to batch any type of request, including
requests to third party servers (e.g., "phone home" requests) that need
to be executed in sequence with container-local requests; in this case
the container API is acting as a proxy (and should take appropriate
security precautions to avoid abuse).
</p>
<p>This optional feature allows a container to accept an arbitrary
sequence of operations while using only one HTTP round trip between
server and client for the overall set of requests and response.
</p>
<h4>9.1 Discovery</h4>

<p>If a container supports batching, it advertises a "batch-proxy" Service in its discovery document:
</p><pre>&lt;Service&gt;
  &lt;Type&gt;http://ns.opensocial.org/batch-proxy/0.8&lt;/Type&gt;
  &lt;URI simple:method="POST"&gt;http://api.example.org/batch-proxy&lt;/URI&gt;
&lt;/Service&gt;
</pre>
<p>The method may be either POST or BATCH. Containers SHOULD support
the BATCH method if possible, but MUST support the POST method. Clients
SHOULD support the BATCH method but MUST be able to fall back to the
POST method.
</p>
<h4>9.2 Semantics</h4>

<p>The semantics of a set of batched requests in this proposal are
exactly the same as sending the same requests individually. In
particular, the server does not provide any atomicity guarantees. The
server is not allowed to reorder or parallelize the requests unless it
can do so without client-visible side effects. The simplest server
implementation is to loop over the requests, executing each in turn,
and appending responses into a batch response to send to the client.
</p>
<p>The batch interface is an optional part of OpenSocial. If a server
does not support it, a client falls back to using individual requests
and responses with no changes in semantics. Depending on the exact
situation, it may be more efficient to use individual requests which
can be parallelized and cached, or to use batch serial requests; a goal
with this API is to make it simple for a client to switch between the
two mechanisms and to keep the semantics consistent and
straightforward.
</p>
<p>To this end, a batch request is represented by an envelope HTTP
request sent to a batching proxy resource. The client POSTs the
document described below to the proxy URI, which returns 200 OK when
the contents have been processed (successfully or not) and returns a
response sequence document.
</p>
<p>Both request and response sequence documents are represented by
standard multipart/mixed documents; the individual requests and
responses are represented by standard application/http;version=1.1
documents (see <a href="http://www.w3.org/Protocols/rfc2616-sec19.html#sec19.1">RFC2616, section 19.1</a>).
These documents encapsulate what would be sent over the wire for a
standard, stand-alone HTTP request. An example request with two parts:
</p><pre>POST /batch-proxy HTTP/1.1
Host: api.example.org
Authorization: OAuth ...request auth[nz] context elided...
Content-Type: multipart/mixed; boundary=batch-a73hdj3dy3mm347ddjjdf

-batch-a73hdj3dy3mm347ddjjdf
Content-Type: application/http;version=1.1
Content-Transfer-Encoding: binary

POST /people/@me/@all HTTP/1.1
Host: api.example.org
Content-Type: application/json

...representation of new Person elided...

-batch-a73hdj3dy3mm347ddjjdf
Content-Type: application/http;version=1.1
Content-Transfer-Encoding: binary

GET /people/@me/@friends?startPage=5&amp;count=10&amp;format=json
Host: api.example.org
If-None-Match: "837dyfkdi39df"
</pre>
<p>The response:
</p>
<pre>HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch-a73hdj3dy3mm347ddjjdf

-batch-a73hdj3dy3mm347ddjjdf
Content-Type: application/http;version=1.1
Content-Transfer-Encoding: binary

201 Created
Location: http://api.example.org/people/example.org:38ge838389993/@all/api.example.org:5ea3gh838kjk34834
ETag: "993hhhgjgkkd"

-batch-a73hdj3dy3mm347ddjjdf
Content-Type: application/http;version=1.1
Content-Transfer-Encoding: binary

304 Not Modified
ETag: "837dyfkdi39df"
</pre>
<p>In this case, the friend add succeeded and the response to the
retrieval of page 5 of the friends list indicates that page 5 didn't
change (the friend was added below that page's last entry). If the
resource had changed, of course, there would be a list of the friends
in the response.
</p>
<p>Only the top level request can specify overall request related
things such as keepalives and content transfer encoding. The top level
request response code is:
</p>
<ul>
<li>
200 if the batch was processed, even partially;
</li><li>A 4xx error if the batch document itself was bad and could not
be processed (note that a bad document might not be detected before
partial processing occurs, so clients cannot rely on the server to do
syntax checking). An example of this would be a document that is not of
type multipart/mixed.
</li><li>A 5xx error if the proxy batch service itself is having severe problems.
</li></ul>
<p>Individual responses use the HTTP response codes they would have
used had they been executed individually. Requests and responses are
matched by position, and the server guarantees that if it sends back a
response, the nth response is for the nth request. It does not
guarantee that the number of responses matches the number of requests;
in particular, network problems might truncate a response document or
drop a connection, and in this case clients are left not knowing the
status of the remaining responses. If a server needs to indicate that a
particular sub-request timed out without any indication of whether it
succeeded or failed, it should use "X-Batch-Status: 504 Gateway
Timeout" to indicate that it has a known unknown. Clients seeing a 504
sub-response should be advised that the request may have completed
before timing out.
</p>
<p>Note that a container MAY support proxying to foreign servers (via
the Host: header); however, servers are not required to support this
and clients SHOULD NOT assume the capability.
</p>
<p>In general, HTTP fields may be added to either the envelope request
or sub-requests. For example, a client may add an Authorization: header
to the envelope request (to authorize itself to the proxy service) and
also add Authorization: header(s) to different sub-requests (to
authorize itself to other services).
</p>
<p>(This extension generally follows the proposal at <a href="http://www.snellspace.com/wp/?p=886">http://www.snellspace.com/wp/?p=886</a>, which is also the semantics used by Astoria.) 
</p>
<h3>10. Partial Updates (Optional)</h3>
<p>Partial updates avoid the need to send full representations of data
on updates, especially for People and App Data. The primary use case is
when a client has retrieved a full representation and subsequently
wishes to send a small update to a server. In the most general case,
the client my have a series of small updates (e.g., changing tags on a
large number of contacts) scattered across many resources. It should
also allow for concurrency control. We wish to have a generalized
partial update / patching mechanism to handle such cases. As with the
batching mechanism, it should be optional on the server side; clients
can always fall back to sending full representations back to the server
if it does not support the mechanism.
</p>
<p>The exact syntax is TBD at this point. 
</p>
<h3>11. Messaging (Optional)</h3> 

<p>A social network service may optionally expose a mechanism for
sending short messages between users. The functionality and policies
are parallel to those of the JS API's requestSendMessage.
</p>
<h4>Discovery</h4>

<p>If a container supports messaging, it advertises a "messages" Service in its discovery document:
</p><pre>&lt;Service&gt;
  &lt;Type&gt;http://ns.opensocial.org/messages/0.8&lt;/Type&gt;
  &lt;os:URI-Template&gt;http://api.example.org/messages/{guid}/outbox/{msgid}&lt;/URI-Template&gt;
&lt;/Service&gt;
</pre>
<h4>Semantics</h4>
<p>To create a message and place it in a queue, a client PUTs a message
to an 'outbox' collection resource discovered from the XRDS document:
</p><pre>PUT /messages/{guid}/outbox/{msgid}
</pre>
<p>The outbox is owned by the source user. Placing a message in the
outbox requests that the message be delivered to one or more
recipients. Containers are free to filter or alter the message
according to their own policies (such as security or rate limiting
policies). </p>
<p>The format of the message is the same as an activity, but with an additional set of recipients (osapi:recipient):
</p><pre>&lt;entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:osapi="http://opensocial.org/2008/opensocialapi"&gt;
  &lt;osapi:recipient&gt;example.org:AD38B3886625AAF&lt;/osapi:recipient&gt;
  &lt;osapi:recipient&gt;example.org:997638BAA6F25AD&lt;/osapi:recipient&gt;
  &lt;title&gt;You have an invitation from Joe&lt;/title&gt;
  &lt;id&gt;{msgid}&lt;/id&gt;
  &lt;link rel="alternate" href="http://app.example.org/invites/{msgid}"/&gt;
  &lt;content&gt;Click &lt;a href="http://app.example.org/invites/{msgid}"&gt;here&lt;/a&gt; to review your invitation.&lt;/content&gt;
&lt;/entry&gt;
</pre>
<p>The {msgid} is client generated and SHOULD be globally unique. If a
client does not care about failure cases, it can alternatively use a
standard AtomPub POST to /messages/{source-uid}/outbox and leave
generation of the ID to the container. In either case, the response is
201 Created on success.
</p>
<p>If not supported, the response code should be 403 Not Implemented.
</p>
<p>Typically a container would choose to only allow a PUT to an outbox
where the {guid} equals the requestor id, but this is a container
security policy decision. Containers may choose to allow messaging only
between friends or user other heuristics to prevent spam.
</p>
   
      <div style="height: 11280px;" id="gc-collapsible"></div></div><!-- end gc-pagecontent -->
   </div><!-- end gooey wrapper -->

    </div> <!-- end codesite content -->

<div id="gc-footer" dir="ltr"> 
  <div class="text">
    
      <div class="notice"><div id="notice" style="text-align: center;">
  Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
  the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
  Attribution 2.5 License</a>.
<!-- <rdf:RDF xmlns="http://web.resource.org/cc/" 
              xmlns:dc="http://purl.org/dc/elements/1.1/"
              xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <Work rdf:about="">
    <license rdf:resource="http://creativecommons.org/licenses/by/2.5/" />
  </Work>
  <License rdf:about="http://creativecommons.org/licenses/by/2.5/">
    <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
    <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
    <requires rdf:resource="http://web.resource.org/cc/Notice"/>
    <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
    <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
  </License>
</rdf:RDF> -->
</div>
</div>
    
    ©2008 Google -
    <a href="http://code.google.com/">Code Home</a> -
    <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> -
    <a href="http://www.google.com/privacy.html">Privacy Policy</a> -
    <a href="http://code.google.com/more/">Site Directory</a>
     <br>
     <br>
    Google Code offered in:  
    <a href="http://code.google.com/intl/zh-CN/">中文</a> - 
    <a href="http://code.google.com/">English</a> - 
    <a href="http://code.google.com/intl/pt-BR/">Português</a> - 
    <a href="http://code.google.com/intl/ru/">Pусский</a> - 
    <a href="http://code.google.com/intl/es/">Español</a> - 
    <a href="http://code.google.com/intl/ja/">日本語</a> </div><!-- end gc-footer -->
  </div>
</div><!-- end gc-containter -->
<script src="restfulspec_files/ga.js" type="text/javascript">
</script>
<script type="text/javascript">
  try {
    var pageTracker = _gat._getTracker("UA-18071-1");
    pageTracker._setAllowAnchor(true);
    pageTracker._initData();
    pageTracker._trackPageview(); 
  } catch(e) {}
</script>




  <select size="6" style="position: absolute; display: none;" class="fauxSelect"><option value="zh-CN">中文 (简体)</option><option value="en">English</option><option value="pt-BR">Português (Brasil)</option><option value="ru">Pусский</option><option value="es">Español</option><option value="ja">日本語</option></select><div id="gc-collapsible-arrow"></div><div id="cs-searchresults"><div id="cs-recommended">Suggestions</div><div id="searchResult1"></div><div id="searchResult2"></div><div id="searchResult3"></div><div id="searchResult4"></div><div id="searchResult5"></div><div id="searchResult6"></div><div id="searchResult7"></div></div></body></html>